Google Ads Developer Blog

Upcoming Change to the Enforcement of Temporary IDs with Product Partitions and Listing Groups

2021-03-23T06:36:00.000-07:00

Beginning in May, 2021 we will enforce a requirement that temporary IDs be unique for all objects in newly created listing groups (used for Hotel Ads and Shopping Ads in the Google Ads API) and product partitions (used for Shopping Ads in the AdWords API). This change will affect all versions of both the AdWords and Google Ads APIs.

Temporary IDs must be unique across an entire mutate request–even if the objects are in separate listing group trees or product partition trees.

In order to avoid unnecessary breakages, API users should update their applications to ensure that all temporary IDs used in individual requests are unique.

Here is a snapshot of the expected behavior for requests that continue using non-unique temporary IDs:

API and mutate method	Current Behavior	New Behavior
BatchJobService with the Google Ads API	Customers will receive a non-specific error, meaning it may not specify that the issue is related to temporary IDs.	Customers will start receiving failed operations that contain the error: `MutateError.MUTATE_ERROR_TEMP_ID_ALREADY_EXISTS`
BatchJobService with the AdWords API	Customers will receive a non-specific error, meaning it may not specify that the issue is related to temporary IDs.	Customers will start receiving failed operations that contain the error: `NewEntityCreationError.DUPLICATE_TEMP_IDS`
AdGroupCriterionService or GoogleAdsService.Mutate with the Google Ads API	Customers will not receive an error.	Customers will start receiving the error: `MutateError.MUTATE_ERROR_TEMP_ID_ALREADY_EXISTS`
AdGroupCriterionService with the AdWords API	Customers will not receive an error.	Customers will start receiving the error: `NewEntityCreationError.DUPLICATE_TEMP_IDS`

If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.
- Ben Karl, on behalf of the Google Ads API Team

AdFormat in Search Query Performance Report will start returning UNKNOWN starting 2021-05-12

2021-03-18T13:37:00.000-07:00

On 2021-05-12 we will deprecate the AdFormat column in the Search Query Performance Report for AdWords API and Google Ads scripts. From then onwards, the report will return UNKNOWN for this field. This does not affect the Google Ads API.

The AdFormat column provides the type of creative that was triggered such as text, image, or video. If you still require this information, you can instead select AdGroupId and CreativeId from the same report, then call AdGroupAdService.get() to retrieve the Ad.type field.

This completes the migration that was started in January 2020 to remove AdFormat from all reports.

If you have any questions about this or anything else related to the AdWords API, please reach out to our support team on the forum.

Nick Birnie, Google Ads API Team

Reorganizing Similar Bid Strategies

2021-02-23T10:14:00.002-08:00

Update (March 12, 2021): Updated the language in this post to emphasize that this change is a reorganization of existing features.
The v6 release of the Google Ads API added support for Maximize conversions and Maximize conversion value bid strategies in Search campaigns. This includes a new read-only MaximizeConversions.target_cpa field. Bid strategies having either this new target_cpa field or the read-only MaximizeConversionValue.target_roas field act identically to TargetCpa and TargetRoas bid strategies, respectively. In the future, bid strategies for Search campaigns will be reorganized for simplification.

What’s changing
Starting in April 2021, the Google Ads UI will start allowing some users to create MaximizeConversions and MaximizeConversionValue bid strategies with their target_cpa and target_roas fields set, in lieu of the old-style TargetCpa and TargetRoas bid strategies. This change will gradually ramp-up to more accounts over time.

There will be no impact to bidding behavior due to these changes. The MaximizeConversions bid strategy using the new optional target_cpa setting will still behave like the TargetCpa strategy does today, and likewise, MaximizeConversionValue using the new optional target_roas setting will behave like TargetRoas.

Before	After
`TargetRoas`	`MaximizeConversionValue.target_roas`
`TargetCpa`	`MaximizeConversions.target_cpa`

The target_roas and target_cpa fields will remain read-only to API users until a future version of the API enables mutate functionality. Be on the lookout for such an announcement in the API’s release notes.

What to do
Developers should ensure their code treats Search campaigns that have MaximizeConversions with a set target_cpa field and MaximizeConversionValue with a set target_roas field the same way it treats TargetCpa and TargetRoas bid strategies, respectively.

Developers can continue to create TargetCpa or TargetRoas bid strategies or manage existing TargetCpa or TargetRoas bid strategies, even after we introduce the new representations in April. We will publish an update on the blog when the above fields are mutable, along with several months' notice before we start moving to the new representations of the bid strategies for existing Search campaigns.

If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.
Adam Ohren, Google Ads API Team

Changes to Showcase Shopping ads

2021-02-22T07:54:00.000-08:00

On April 5, 2021, support for Showcase Shopping ads will be removed from the AdWords API. Users will no longer be able to create or update the following Showcase Shopping objects, and attempts to do so will result in the following errors.

Object	Error
AdGroups with adGroupType `SHOPPING_SHOWCASE_ADS`	`OPERATION_NOT_PERMITTED_FOR_CAMPAIGN_TYPE`
AdGroupAds containing ShowcaseAds	`OPERATION_NOT_PERMITTED_FOR_AD_GROUP_TYPE`

Any remaining Showcase ad groups will be set to REMOVED status, and remaining AdGroupAds containing ShowcaseAds will be set to DISABLED status and stop serving. Developers can still retrieve historical metrics for these ads and ad groups by fetching reports that explicitly filter to include REMOVED or DISABLED objects.

This change only affects AdWords API users. Management of Showcase Shopping ads is not supported by Google Ads API or Google Ads scripts.

If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.
Adam Ohren, Google Ads API Team

New Personalized Advertising Policies Enforcement in Google Ads API and AdWords API

2021-02-11T08:07:00.000-08:00

Starting March 25, 2021, we are rolling out a change in the Google Ads API and AdWords API, to require advertisers who apply to the latest Personalized advertising policies to acknowledge these changes in the Google Ads UI. Campaign creation requests via the API will be rejected for these advertisers until they click to accept the changes.

Who will be impacted?
Advertisers promoting housing, employment, or credit products or services to audiences in the U.S. and Canada will be impacted.

What's changing?
You will receive the following errors when trying to create new campaigns via the API if the new policies have not been acknowledge:

API Version	Error Code	Error Message
Google Ads API v6.1	`CampaignError.HEC_AGREEMENT_REQUIRED`	`Customers with Housing, Employment, or Credit ads must accept updated personalized ads policy to continue creating campaigns`
Google Ads API (older versions)	`CampaignError.UNKNOWN`	Same as above.
AdWords API (v201809)	`CampaignService.OperationAccessDenied`	Same as above.

What should you do?

Before March 25, 2021, make sure to add support for the new policy errors in your application.
Ensure that the account administrators have accepted the policy changes in the Google Ads UI following this guide.

If you have any questions or need additional help, contact us through the Google Ads API and AdWords API forum or at googleadsapi-support@google.com.
Fan Wang, Google Ads API Team

Announcing v6.1 of the Google Ads API

2021-02-10T15:44:00.001-08:00

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:

Retrieving and managing recommendations for adding responsive search ads.
Added support for managing user invitations for a Google Ads account.
Added Feed, FeedItem, CampaignFeed, AdGroupFeed, and AdGroupAd resources to the list of resource types returned in queries against the change_event resource.
New conversion metrics by conversion date.
New call_view resource for reporting on call extensions and call only ads.

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

2021-02-09T06:26:00.000-08:00

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 googleadsapi-support@google.com.
Adam Ohren, Google Ads API Team

Changes to phrase match and broad match modifier

2021-02-04T13:28:00.000-08:00

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.
David Wihl, Google Ads API Team

The Invoice Service of Google Ads API is out of beta

2021-02-04T08:01:00.000-08:00

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 googleadsapi-support@google.com.
Pierrick Voulet, Google Ads API Team

Disabling "lead" category mutates in AdWords API

2021-02-03T07:30:00.000-08:00

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.
David Wihl, Google Ads API Team

Ad Policy Error Management is evolving in Google Ads API

2021-01-15T13:05:00.001-08:00

Update (February 11, 2021): Added APP_AD and APP_ENGAGEMENT_AD to the list of ad types that are impacted by this change.

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:

APP_AD
APP_ENGAGEMENT_AD
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:

Request: For each operation, the Google Ads API will only take into account the requested exemptions that are listed in PolicyValidationParameter.ignorable_policy_topics from the field policy_validation_parameter, not in PolicyValidationParameter.exempt_policy_violation_keys.
Response: The Google Ads API will only return ad policy errors as PolicyFindingErrors in the field GoogleAdsError.error_code and provide details as PolicyFindingDetails in the field GoogleAdsError.details, not as PolicyViolationErrors and PolicyViolationDetails.

What’s Not Changing

All the ad policies will remain and all the ad policy checks will still occur.
AdWords API
The ad policy status information AdGroupAdPolicySummary will remain accessible by querying the field AdGroupAd.policy_summary.

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 googleadsapi-support@google.com.
Pierrick Voulet, Google Ads API Team

Changes to conversion columns in AdWords API and Scripts

2021-01-14T14:22:00.000-08:00

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

2021-01-12T09:41:00.000-08:00

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

2020-11-09T07:00:00.000-08:00

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

Target Spend Migration for Maximize Clicks Bid Strategies

2020-10-29T11:06:00.000-07:00

Starting January 18, 2021, we will start migrating Maximize Clicks bid strategies that still utilize the deprecated target_spend setting to use campaign daily budget pacing instead. This follows last year’s sunset of the target_spend field for Maximize Clicks. After that sunset went into effect, Google Ads has prevented users from creating any new Maximize Clicks strategies that have a target_spend setting.

What’s changing

As part of this migration, any Maximize Clicks bid strategies that still use the target_spend setting may have their maximum CPC bid limit lowered to minimize the performance impact that may result from this change. This would affect the following API fields:

Fields whose values may be lowered as part of the January 18, 2021, migration:
AdWords API	Google Ads API
TargetSpendBiddingScheme.bidCeiling	TargetSpend.cpc_bid_ceiling_micros

What you can do

You can avoid the above changes by removing the target spend setting on your campaigns’ bidding strategies before January 18, 2021. To do so, unset the following field (set its value to 0) on any existing Maximize Clicks bid strategies:

Fields to unset (set to `0`) to avoid the migration:
AdWords API	Google Ads API
TargetSpendBiddingScheme.spendTarget	TargetSpend.spend_target_micros

If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.

Adam Ohren, Google Ads API Team

Google Ads and AdWords APIs upgrading authorization scope to "sensitive"

2020-10-15T06:02:00.000-07:00

As of October 1, 2020, any Google Cloud app used to obtain credentials for the Google Ads API or AdWords API scope (https://www.googleapis.com/auth/adwords) in its projects (i.e. any new AdWords API or Google Ads API developers) will need to undergo a Google OAuth verification to avoid an unverified app screen for its users. An app, in this context, is defined as a unique OAuth 2.0 Client ID in Google Cloud. This verification is independent and in addition to any reviews conducted as part of the developer token approval process.

There is no cost for the Google verification, which typically completes in 3 to 5 business days. Information on how this process fits in the larger task of authorizing requests can be found in our guide. The verification status of a given app can be viewed at the OAuth consent screen of a Google Cloud Project.

Apps already using the Google Ads API or AdWords API scope prior to October 1, 2020 are not currently affected by this policy. However, this policy will be applied to all apps at a later date in 2021, and it is recommended that all apps undergo the Google OAuth verification process at their earliest convenience to avoid any business interruptions.

If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.
- Devin Chasanoff, on behalf of the Google Ads API Team

Announcing the Google Ads API is out of beta

2020-09-21T10:04:00.000-07:00

We are excited to announce that the Google Ads API is now generally available. This means you can use the Google Ads API for your production applications with confidence that prior performance issues have all been addressed. Batch processing is now available to everyone.

The AdWords API will continue to be supported. We will announce a deprecation schedule at a later date. We will continue to add more features in upcoming releases to reach full parity with the AdWords API.

Where can I learn more?
Get started with the following resources:

If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.
Nadine Wang, on behalf of the Google Ads API Team

Conversion Category Changes in AdWords API, Google Ads API, and Google Ads scripts

2020-09-08T09:06:00.002-07:00

Update (Feb 1, 2021): Correction to some of the category mappings.

Since May 2020, when you sign in to your Google Ads account you may be prompted to upgrade each of your conversion actions to the new conversion categories. The updated conversion categories provide more granularity to describe the conversion actions that are the most meaningful for your business. More details can be found in this Google Ads Help Center article.

Starting October 15th 2020, these suggestions will be automatically applied if you haven’t already accepted them. Google Ads API, AdWords API and Google Ads Scripts users will see the following changes:

If you are using the Google Ads API, the new conversion categories are already available in ConversionActionCategoryEnum. No further action is needed.

If you are using the AdWords API, since we are not releasing a new version for the AdWords API, the new conversion category types will be translated to the existing ConversionTracker.Category enum values, based on the mapping below:

New Conversion Category	ConversionTracker.Category
Add to cart	`LEAD`
Begin checkout	`LEAD`
Purchase	`PURCHASE`
Subscribe	`PURCHASE`
Sign-up	`SIGNUP`
Phone call leads	`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`

Therefore, if you are using the AdWords API to retrieve conversion category types (via reports or services), you will still see existing conversion category types being returned based on the mapping above, which will be different from the migrated new types in Google Ads UI.

AdWords API users can still create conversion actions using the existing category types. The AdWords API will automatically translate the created conversions to new category types, based on machine learning models. You can find code examples on how to set category type for conversion actions on the AdWords API developer site.

If you are using Google Ads scripts, when you select or filter on the report field ConversionCategoryName, you will see the same existing category types as the ones used in AdWords API, based on the mapping in the above table.

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

Announcing v5 of the Google Ads API beta

2020-08-26T13:08:00.000-07:00

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

Here are the highlights:

Return metrics for entities not formally supported in the API, such as Discovery campaigns, are now available. These entities will show UNKNOWN enum values returned. See the release notes for more details.
New request parameter to opt into returning all mutable fields in the response during a mutate.
The API is moving towards using field presence such as optional string and optional double instead of wrapper types such as StringValue and DoubleValue. Your code will be easier to use and simplifies the API with payloads that are significantly smaller. Approximately half of our resources have been updated in this release. The full list is in the migration guide, and our code examples have been updated. The rest of the resources will change to field presence in a future release.
Subfields of AdGroupAd.policy_summary are now selectable. Non-repeated subfields of AdGroupAd.policy_summary are now filterable.
Support for Keyword Planner:
- Added KeywordPlanKeywordHistoricalMetrics.close_variants to return the close variant keywords that have been merged to compute the historical metrics.
- Added KeywordPlanService.GenerateForecastTimeSeries that returns the weekly forecast trend for Keyword Plan for the next 52 weeks.

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

Announcing v4 of the Google Ads API beta

2020-07-08T14:14:00.000-07:00

Today, we’re announcing the v4 release of the Google Ads API beta. To use the v4 features, update your client library. If you are upgrading from v1, v2, or v3, some of your code may require changes when you switch to the new v4 endpoint. For more information on breaking changes, see the migration guide. If you are using v1, upgrade by July 29, 2020.

Here are the highlights:

Local campaigns. Local campaigns streamline the process for you, making it easy to promote your stores across Google’s largest properties including the Google Search Network, Maps, YouTube, and the Google Display Network.
Support for retrieving and reporting on Smart campaigns.
Support for account-level optimization score.
Keyword Planning. See the Planning section in the release notes for details.
Linking third party app analytics accounts to Google Ads accounts. See the Account Management section in the release notes for details.

Where can I learn more?
The following resources can help you get going with the Google Ads API:

The updated client libraries and code examples will be published next week. If you have any questions or need additional help, contact us via the forum.
Nadine Wang, on behalf of the Google Ads API Team

Entity IDs as 64-bit in AdWords API, Google Ads API beta, Google Ads scripts, and Content API for Shopping

2020-06-15T01:30:00.000-07:00

In the AdWords API, the Google Ads API beta, Google Ads scripts, and the Content API for Shopping, all entity IDs are 64-bit signed integers. They are of type:

xsd:long in the AdWords API
INT64 in the Google Ads API
number or string in Google Ads scripts
string in REST and as INT64 for client libraries in Content API for Shopping

Applications that integrate with the API should handle ID values in that range.

Historically, the following IDs were within the maximum value of 32-bit signed integer, but will soon be exceeding this range. Over the years, all of you have been so productive that we need to make sure 64-bit signed integers are available to allow the creation of more entities with unique IDs. This was announced starting in July 2019. To avoid any issues, please make sure your applications handle these IDs within a range of 64-bit signed integer values. Also make sure that your application is ready to support a 64-bit signed integer for any other entity IDs not listed below.

Which IDs are affected in the AdWords API and the Google Ads API beta?

	AdWords API	Google Ads API beta
Bidding Strategy	`BiddingStrategyConfiguration.bidding_strategy_id` `BiddingStrategyId` (multiple reports)	`BiddingStrategy.id`
Budget	`BudgetOrder.id`	`AccountBudget.id` `BillingSetup.id`
User List	`UserList.id` `CriterionUserList.userListId` `CLICK_PERFORMANCE_REPORT.UserListId` `AUDIENCE_PERFORMANCE_REPORT.Id`	`UserList.id`
Shopping Campaigns	`ServiceLink.serviceLinkId` `ShoppingSetting.merchantId` `SHOPPING_PERFORMANCE_REPORT.MerchantId` `SHOPPING_PERFORMANCE_REPORT.AggregatorId`	`MerchantCenterLink.id` `ShoppingSetting.merchant_id` `segments.product_merchant_id` `segments.product_aggregator_id`
Conversion Action	`ConversionTracker.id` `ConversionTrackerId` (multiple reports) `ConversionTracker.originalConversionTypeId`	`ConversionAction.id`
Account Conversion Tracking Configuration	`ConversionTrackingSettings.effectiveConversionTrackingId`	`ConversionTrackingSetting.conversion_tracking_id` `ConversionTrackingSetting. cross_account_conversion_tracking_id`

Which IDs are affected in Google Ads scripts?
JavaScript can only accurately represent integers up to 53 bits, so it's strongly advised that you begin treating all IDs in Google Ads scripts as string to avoid any possible future errors with high ID numbers.

	Google Ads scripts
Bidding Strategy	`AdsApp.BiddingStrategy.getId()`
Budget	`AdsApp.BillingAccount.getId()` `AdsApp.BudgetOrder.getId()`
User List	`AdsApp.Audience.getId()` `AdsApp.ExcludedAudience.getId()` `AdsApp.UserList.getId()` `AdsApp.ShoppingCampaignAudience.getAudienceId()` `AdsApp.ShoppingCampaignAudienceBuilder.withAudienceId()` `AdsApp.ShoppingCampaignAudienceSelector.withIds()` `getAudienceId()` and `withAudienceId()` for all Targeting -> Audience `Search` methods.

Which IDs are affected in the Content API for Shopping?
All IDs are returned as string in REST and as INT64 in the client libraries. If you convert IDs to a number in your application, please make sure the application can handle 64-bit signed integers. An example of this is merchant ID that is set in the client library’s configuration or in the REST URL.

Content API for Shopping

Merchant Center AccountIdentifier.merchantId

Order.merchantId

OrdersCustomBatchRequestEntry.merchantId

RegionalinventoryCustomBatchRequestEntry.merchantId

ProductsCustomBatchRequestEntry.merchantId

ProductstatusesCustomBatchRequestEntry.merchantId

AccountsCustomBatchRequestEntry.merchantId

OrderReportDisbursement.merchantId

OrderReportTransaction.merchantId

LocalinventoryCustomBatchRequestEntry.merchantId

ReturnpolicyCustomBatchRequestEntry.merchantId

Shopping Campaign AccountIdentifier.aggregatorId

	Content API for Shopping
Merchant Center	`AccountIdentifier.merchantId` `Order.merchantId` `OrdersCustomBatchRequestEntry.merchantId` `RegionalinventoryCustomBatchRequestEntry.merchantId` `ProductsCustomBatchRequestEntry.merchantId` `ProductstatusesCustomBatchRequestEntry.merchantId` `AccountsCustomBatchRequestEntry.merchantId` `OrderReportDisbursement.merchantId` `OrderReportTransaction.merchantId` `LocalinventoryCustomBatchRequestEntry.merchantId` `ReturnpolicyCustomBatchRequestEntry.merchantId`
Shopping Campaign	`AccountIdentifier.aggregatorId`

Where can I get support?
If you have any API questions or need help, you can reach us at:

AdWords API and Google Ads API beta forum or googleadsapi-support@google.com.
Google Ads scripts forum.
Content API for Shopping forum.

Nadine Wang, on behalf of the entire Google Ads Team

Update on the Google Ads API Beta

2020-05-26T10:01:00.000-07:00

Since our last announcement in July, we've made several updates to improve the performance of the Google Ads API. Your feedback was essential to us in making these improvements and will continue to be throughout the remainder of the Beta.

What has been fixed?
Over the past several months, we've rolled out performance improvements to Google Ads API read and mutate functionality. Some of these updates are visible in recent versions of the API, such as the launch of GoogleAdsService.SearchStream() in v3_0, while other improvements have sped up the response times of existing services and methods.

What's next for the Google Ads API Beta?
It is our top priority to get the Google Ads API ready for general availability. This involves rolling out features for key user journeys, for example: a service for asynchronous batch updates. If you have any feedback on the API's readiness to address your tool's requirements, we'd like to hear from you!

Which API should I use?
Throughout the remainder of the Beta, the AdWords API will continue to be the primary API for programmatically accessing and managing Google Ads campaigns. When deciding whether to use the Google Ads API Beta to run production systems, please keep in mind that we may release updates in preparation for general availability. As a reminder, changes will be released in new versions of the Google Ads API Beta. They will not affect your existing code unless announced otherwise on this blog.

If you have any feedback or questions regarding the performance, feature availability and overall usability of the Google Ads API Beta, please contact us at googleadsapi-support@google.com.
-- The Google Ads API team

Reminder about sunset, creation of target spend field for Maximize Clicks strategies in Ads APIs

2020-05-18T09:15:00.002-07:00

On July 31st, 2019 we began to sunset the target spend field for Maximize Clicks bidding strategies. At the time, the feature was only removed from the UI, and the Google Ads APIs were not impacted.

Starting on June 30th, 2020, we will continue to sunset the target spend field in the Google Ads APIs as per our original blog post. This will affect all versions of both the AdWords API and the Google Ads API. The following behaviors will be blocked:

Populating the target spend field on existing standard and portfolio strategies
Attaching portfolio strategies that have the deprecated field set to campaigns

Read on to see how this will affect your API usage:

	Affected Target Spend Fields
Google Ads API	`campaign.target_spend.target_spend_micros` `bidding_strategy.target_spend.target_spend_micros`
AdWords API	`Campaign.BiddingStrategyConfiguration.TargetSpendBiddingScheme.spendTarget` `SharedBiddingStrategy.TargetSpendBiddingScheme.spendTarget`

Change Description
Any mutate operations that set a target spend field for the first time will return an error. You will be able to update a target spend field that currently contains a value, but you cannot set previously empty fields to a new value. Additionally, any operation attaching a bidding strategy to a campaign where that bidding strategy has a value set for a target spend field, will throw an error. To manage Target Spend on any new campaigns, we recommend using campaign budget. In each of these cases an error will be thrown.

Performing any of the actions listed above will generate one of the following errors:

OPERATION_NOT_PERMITTED_FOR_CONTEXT
UNSUPPORTED_FIELD_IS_SET

If you have any questions about this change or any other API feature, please contact us via the forum.
- Cory Liseno, Google Ads API Team

Announcing v3_1 of the Google Ads API beta

2020-04-29T13:00:00.000-07:00

Today we’re announcing the v3_1 release of the Google Ads API beta. To use the v3_1 features, please update your client library. If you are upgrading from v1 or v2, some of your code may require changes when you switch to the new v3 endpoint. Please see the migration guide for more information on breaking changes.

Here are the highlights:

Added support for retrieving campaign optimization score in Campaign.optimization_score.
Added new conversion action categories to ConversionActionCategory. See the release notes for details.
Added a new service OfflineUserDataJobService which supports asynchronous upload of Customer Match data and store sales (direct upload) data. These features are whitelisted.
Added support for retrieving the paying manager customer with PaymentsAccount.paying_manager_customer when making a request to PaymentsAccountService.ListPaymentsAccounts().

Where can I learn more?
The following resources can help you get going with the Google Ads API:

The updated client libraries and code examples will be published next week. If you have any questions or need additional help, please contact us via the forum.
Nadine Wang, on behalf of the Google Ads API Team

Google Ads conversion reporting issues starting April 9

2020-04-10T18:23:00.000-07:00

Update (April 10, 2020 19:35 PST): Conversion data in all reports has been fixed.

An issue that impacted Google Ads reporting for Search and Shopping conversions occurring between April 9 and April 10 (Pacific Time) for advertisers using non-last click attribution models has been fixed and the data is now correct in all reports.
If you downloaded any of the fields in the table below or any derivative custom columns using the AdWords API, Google Ads API and Google Ads scriptsbetween April 9th 8:00 PM PST and April 10th 7:20 PM PST, you may have incorrect data in your systems. Please re-download the affected fields to ensure accurate conversions reporting.
We appreciate your patience as we worked to resolve this issue as quickly as possible.

AdWords API	Google Ads API beta
Conversions ConversionValue ConversionRate ValuePerConversion CostPerConversion AllConversions AllConversionValue AllConversionRate ValuePerAllConversion CostPerAllConversion CurrentModelAttributedConversions CurrentModelAttributedConversionValue ValuePerCurrentModelAttributedConversion CostPerCurrentModelAttributedConversion	metrics.all_conversions metrics.all_conversions_from_click_to_call metrics.all_conversions_from_interactions_rate metrics.all_conversions_from_interactions_value_per_interaction metrics.all_conversions_value metrics.all_conversions_value_per_cost metrics.conversions metrics.conversions_from_interactions_rate metrics.conversions_from_interactions_value_per_interaction metrics.conversions_value metrics.conversions_value_per_cost metrics.cost_per_all_conversions metrics.cost_per_conversion metrics.cost_per_current_model_attributed_conversion metrics.cross_device_conversions metrics.current_model_attributed_conversions metrics.current_model_attributed_conversions_from_interactions_rate metrics.current_model_attributed_conversions_from_interactions_value_per_interaction metrics.current_model_attributed_conversions_value metrics.current_model_attributed_conversions_value_per_cost metrics.value_per_all_conversions metrics.value_per_conversion metrics.value_per_current_model_attributed_conversion

AdWords API

Google Ads API beta

Conversions
ConversionValue
ConversionRate
ValuePerConversion
CostPerConversion
AllConversions
AllConversionValue
AllConversionRate
ValuePerAllConversion
CostPerAllConversion
CurrentModelAttributedConversions
CurrentModelAttributedConversionValue
ValuePerCurrentModelAttributedConversion
CostPerCurrentModelAttributedConversion

metrics.all_conversions
metrics.all_conversions_from_click_to_call
metrics.all_conversions_from_interactions_rate
metrics.all_conversions_from_interactions_value_per_interaction
metrics.all_conversions_value
metrics.all_conversions_value_per_cost
metrics.conversions
metrics.conversions_from_interactions_rate
metrics.conversions_from_interactions_value_per_interaction
metrics.conversions_value
metrics.conversions_value_per_cost
metrics.cost_per_all_conversions
metrics.cost_per_conversion
metrics.cost_per_current_model_attributed_conversion
metrics.cross_device_conversions
metrics.current_model_attributed_conversions
metrics.current_model_attributed_conversions_from_interactions_rate
metrics.current_model_attributed_conversions_from_interactions_value_per_interaction
metrics.current_model_attributed_conversions_value
metrics.current_model_attributed_conversions_value_per_cost
metrics.value_per_all_conversions
metrics.value_per_conversion
metrics.value_per_current_model_attributed_conversion

On April 9, 2020 at approximately 8pm PST, a bug caused Google Ads Search and Shopping conversions occurring between April 9 12:01 AM PST onwards to be underreported for advertisers using non-last click attribution models. This bug impacts reports in all Google Ads interfaces, including any report data downloaded via the AdWords API, Google Ads API and Google Ads scripts. Google Ads bid strategies are not impacted by this issue.
We are actively working on fixing the bug and correcting the conversion data.

- Josh Radcliff, Google Ads API Team