Tag Archives: google_ads_api

Google Ads API v17 sunset reminder

Google Ads API v17 will sunset on June 4, 2025. After this date, all v17 API requests will begin to fail. Migrate to a newer version prior to June 4, 2025 to ensure your API access is unaffected.

Here are some resources to help you with the migration: You can view a list of methods and services your project has recently called using the Google Cloud Console:
  1. In the Google Cloud Console, open the APIs & Services tab.
  2. In the table, click Google Ads API.
  3. On the METRICS subtab, you should see your recent requests plotted on each graph. You can see which methods you've sent requests to in the Methods table. The method name includes a Google Ads API version, a service, and a method name, such as google.ads.googleads.v17.services.GoogleAdsService.Mutate.
  4. (Optional) Choose the timeframe you want to view for your requests.
If you have questions while you’re upgrading, reach out to us on the forum or at [email protected].
Benji Rothman, Google Ads API Team

Announcing v19.1 of the Google Ads API

Today, we’re announcing the v19.1 release of the Google Ads API. To use any of the v19.1 features, you must upgrade your client libraries and client code. The updated client libraries and code examples will be published next week. This release includes no breaking changes and maintains backwards compatibility for those who have already upgraded to v19.

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.

 - , Google Ads API Team

Google Ads API Introducing New Error Codes for Invalid Developer Tokens Starting April 28, 2025

Previously, if any Google Ads API request had an invalid developer token, the API returned an OAUTH_TOKEN_HEADER_INVALID error, which is also used for other invalid request header values. To make it clear when the authentication error is specifically caused by an invalid developer token, we are changing the API to return a new error code, DEVELOPER_TOKEN_INVALID, for version v19.1 of the Google Ads API. All API versions before v19 will handle invalid developer tokens by throwing a DEVELOPER_TOKEN_NOT_APPROVED error instead. If you are using version v19 of the API with our client libraries, you will need to update to the latest version of the client libraries after the v19.1 release. These changes will be effective starting April 28, 2025.

Anyone who has already set up the Google Ads API to make successful calls are highly unlikely to be affected by this change. It is mainly meant to improve the experience of new developers onboarding to the API.

If you have any questions, please ask them in the Google Ads API forum. We're here to help!

 - Dora Sun - Google Ads API Team

Upcoming Performance Max campaign migration to enable brand guidelines

Starting on May 1, 2025, we will begin to automatically enable brand guidelines for Performance Max campaigns that use the same brand assets (BUSINESS_NAME, LOGO, and LANDSCAPE_LOGO) across all asset groups.

Please note the rollout timelines:
  • For Google Ads UI users: The process will begin on May 1, 2025 for customer IDs that exclusively manage their campaigns using the UI.
  • For API users: This process will begin on June 1, 2025.
The overall process across all campaigns is expected to be complete by July 31, 2025.

Important Notes:
  • Only campaigns using consistent business names and logo assets across all asset groups will be automatically migrated. Campaigns with variations in these assets will not be migrated.
  • All eligible Performance Max campaigns under a customer ID will be migrated simultaneously.
  • After migration, each migrated campaign will have its own set of brand assets stored at the campaign level using CampaignAsset.
  • You can tell if a campaign has been migrated by checking its Campaign.brand_guidelines_enabled field.
Actions Required
If your application creates asset groups, update your code to check the campaign’s Campaign.brand_guidelines_enabled field. This will tell you whether to include brand assets in the new asset group.

If your application modifies brand assets, update your code to check the campaign’s Campaign.brand_guidelines_enabled field. This will tell you where to save the brand asset; either on a campaign using a CampaignAsset or on an asset group using an AssetGroupAsset.

To avoid extra steps later, we strongly recommend migrating all of your campaigns now using CampaignService.EnablePMaxBrandGuidelines. If you migrate your campaigns manually, each CampaignService.EnablePMaxBrandGuidelines request can only include 10 EnableOperations.

If you have any questions or need help, check out the Google Ads API support page for options.
 - Sarah Pollack, Google Ads API Team

Upcoming change to LowerTargetRoas recommendations in the Google Ads API and Google Ads scripts

As of v17 of the Google Ads API, recommendations of type LOWER_TARGET_ROAS have included a current_average_target_micros as a whole currency value instead of a micros value (where one million is equivalent to one currency unit) as indicated by the field name. On April 23, 2025, we are rolling out a fix to populate current_average_target_micros with the micros value.

Note that as a result of the incorrect unit, the currently returned current_average_target_micros value is truncated and is therefore less precise than the micros equivalent. If you were converting the existing value to micros by multiplying by 1,000,000, the resulting value wouldn't necessarily be correct because any digits past the first position are dropped. For example, a current_average_target_micros value of 5 might have been converted to 5,000,000 in micros before the change, but could be returned as 5,750,000 (more precise) after the change.

What do I need to do?

If you use the Google Ads API or Google Ads scripts to query the recommendation resource for recommendations of type LOWER_TARGET_ROAS, and your application logic uses the current_average_target_micros field, you must update your application to treat the value as micros instead of a whole budget value for when the change takes effect on April 23, 2025.

If you have any questions or need help, check out the Google Ads API support page for options.

 - Laura Chevalier, Google Ads API Team

REST code examples now available for the Google Ads API

Historically, we have always heard from the Google Ads API developer community that code examples are one of the most useful tools to learn about the API and its features. For a long time, however, our API documentation offered code examples for the Google Ads client libraries, but not for REST. We've heard requests from the community to offer more REST code examples, and so we've been working hard to create and integrate a rich set of REST examples directly into our developer documentation.

Now, alongside client library examples, you'll find corresponding REST examples showing you exactly how to structure your curl commands or equivalent code in your preferred language to perform common operations like:
  • Create customer accounts
  • List accessible accounts
  • Manage recommendations
  • Generate keyword ideas
  • And more!
You can find these examples in relevant sections of the Google Ads API documentation on our developer site. For instance, when you look at the guide for listing accessible accounts, you'll now see a "cURL" tab alongside other language options, providing a clear and concise REST-based example.

At the moment, we've added a small, but substantial, subset of examples. We're adding more soon.

Have ideas for additional REST examples?
You can help us prioritize which examples to add and also help implement them. To request a specific code example, open an issue on the REST code examples GitHub repository. You can also open pull requests to help create new examples, or expand the existing ones. Our team will review your submission, and your contribution could help other Google Ads API users.

We hope this addition of REST examples, driven by your valuable feedback, will significantly improve the development experience for a wide range of Google Ads API users. We're excited to see how these examples help you build even more innovative solutions.
 - Mattia Tommasone, Google Ads API Team

Improved Change Tracking in Google Ads API

Over the next several Google Ads API updates, we'll be adding new types of resources you can track using the ChangeStatus feature.

What this means for you:
  • More detailed tracking: You'll soon be able to better track changes to your Google Ads accounts.
  • Important - Check for UNKNOWN changes: Even in older versions of the API, you might start seeing new change entries. These entries will show up as UNKNOWN resource types because the older versions won’t support the new values.
How to prepare:
  • Handle UNKNOWN: If your app uses ChangeStatus, make sure it can handle entries with a resource type of UNKNOWN. This will prevent errors when the new types are added.
  • Update to the latest API version: Once the new version is released, updating your app will show the correct, specific names of the new change types instead of UNKNOWN.
  • We'll announce the exact new resource types in the release notes when the update is live.
If you have any questions, please ask them in the Google Ads API forum. We're here to help!
- Mike Cloonan, Google Ads API Team

Upcoming changes to CustomerService in Google Ads API

We are introducing several changes to the CustomerService.CreateCustomerClient method to align the Google Ads API with how Google Ads UI handles new account creation functionality. These changes will take effect on March 17, 2025.

New error codes for policy enforcement
In order to limit abuse, the Google Ads API introduced two new error codes in the version v19 of the API for the purpose of policy enforcement.
  1. Google Ads manager accounts that do not have a certain threshold of spending or a certain number of active child accounts without policy issues (for example, not suspended or closed for policy violations) will be ineligible to create child accounts under them. Developers will receive a CustomerError.CREATION_DENIED_INELIGIBLE_MCC error code in the upcoming version v19 of the Google Ads API. To fix the issue, link a Google Ads account that is compliant with the Google policies and meets the threshold spending levels under your manager account.
  2. Google Ads manager accounts that have been flagged for policy violations related to account creation will no longer be able to create child accounts under them. Developers will receive a CustomerError.CREATION_DENIED_FOR_POLICY_VIOLATION error code in the upcoming version v19 of the Google Ads API.
In both these cases, existing API versions (v18 and older) will throw a ContextError.OPERATION_NOT_PERMITTED_FOR_CONTEXT error instead.

Quota limits for account creation
The Google Ads API will enforce limits on creation of new Google Ads accounts. Developers will receive a QuotaError.RESOURCE_EXHAUSTED error once the limits are reached. The retry_delay field of the quota_error_details contains additional details on how long you should wait before retrying the API call. We do not expect most developers to be affected by these limits.

What do I need to do?
If your application uses the Google Ads API to create new Google Ads accounts, you should review your code to ensure that your application correctly handles these new error codes.

If you have any questions or need help, check out the Google Ads API support page for options.Reach out to the Google Ads product support team for any questions related to account policies.
 - , Google Ads API Team

Announcing v19 of the Google Ads API

Today, we’re announcing the v19 release of the Google Ads API. To use some of the v19 features, you will need to upgrade your client libraries and client code. The updated client libraries and code examples will be published next week.

Here are the highlights:
  • Added support automatically generating enhanced video assets for Performance Max campaigns.
  • Removed all feed-related entities from the Google Ads API like Feed, FeedMapping, FeedService, AdGroupFeed, feed_placeholder_view. Users should now use assets to achieve the same purpose.
  • Demand Gen ads now support 9:16 portrait image assets. Use DemandGenMultiAssetAdInfo.tall_portrait_marketing_images to include these assets in your ads.
  • Added more methods to DataLinkService for updating and removing previously created DataLink for YouTube.
  • ValueRuleItineraryAdvanceBookingWindow now supports targeting for travel searches that take place today.
  • Removed support for VIDEO_OUTSTREAM.
  • (For allowlisted accounts only) Updates to brand guidelines
    • Brand guidelines can now be enabled for Performance Max campaigns during campaign creation. We also added a new CampaignService.EnablePMaxBrandGuidelines which allows you to enable brand guidelines for existing Performance Max campaigns.
    • You can set the brand guidelines’ details such as font family and colors using Campaign.brand_guidelines.
  • (For allowlisted accounts only) Added support for message assets through Asset.business_message_asset.
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.
 - Thanet Knack Praneenararat, on behalf of the Google Ads API Team

Update to Customer Match membership expiration starting April 7, 2025

Starting on April 7, 2025, a new maximum membership duration of 540 days will gradually roll out for Customer Match lists in Google Ads and Display & Video 360 platforms. This change is being made to better align with Customer Match best practices.

From this date, existing lists configured to have no membership expiration set or membership expiration greater than 540 days will be updated to use the maximum membership duration of 540 days, and a membership duration of 540 days will be retroactively applied to all those existing members that have a longer duration. The reflected list size decreases as memberships expire. Campaigns targeting too small a segment of users can’t serve ads and may automatically pause. Refresh your Customer Match list before April 7, 2025 to renew memberships or replace the expired Customer Match lists with up-to-date lists to ensure that your ad campaigns are not interrupted.

With a set membership duration, you will need to start refreshing your list regularly by re-uploading customer data to your lists. If you do not, the list size will get smaller over time. Refer to this article to learn more about Customer Match.

Required actions for Google Ads API users

Starting on April 7, 2025, requests to set the UserList.membership_life_span field in the Google Ads API to greater than 540 will return a RangeError.TOO_HIGH error. We recommend you check your current implementation to make sure you no longer set the field value to greater than 540.

For existing user lists with membership_life_span field in the Google Ads API greater than 540, starting from April 7, 2025 customer data user lists will be automatically migrated to have a membership life span of the maximum 540 days. If you need to update your code to regularly refresh your customer lists, check out our guide for examples.

No action is required if you do not set the membership_life_span field in the Google Ads API and you regularly refresh your customer lists. Leaving the field unset has the same effect as setting it to the maximum 540 days value.

If you run into issues or have questions about these changes, please contact us using our Google Ads API forum.

Required actions for Display & Video 360 API users

Starting on April 7, 2025, firstAndThirdPartyAudiences.create and firstAndThirdPartyAudiences.patch requests to the Display & Video 360 API that set the membershipDurationDays field to greater than 540 will return a 400 error. Setting the membershipDurationDays field is required when you create a Customer Match list, so we recommend that you check your current implementation to make sure you no longer set the field to a value greater than 540.

From April 7, 2025, existing Customer Match list with a membershipDurationDays field set to a value greater than 540 days will be automatically migrated to a membership duration of the new maximum 540 days. After this date, you will need to regularly refresh your Customer Match list. See our guide for examples on how to update your Customer Match list.

If you run into issues or have questions about these changes, please contact us using our Display & Video 360 API Technical support contact form.

- Da Yang, Google Ads API Team
- Trevor Mulchay, Display & Video 360 API Team